Copyright: ® AA-Software International, 1994


AAVBSORT.DLL V1.0
Documentation

Copyright © 1994 AA-Software International
All Rights Reserved
Shareware Distribution
Roquefort-Les-Pins, France
AA-Software International is applying for membership
in the Association of Shareware Professionals (ASP)

What It Does

Quick Start Example

Benefits of Registering

How to Register

Installing AAVBSORT

AAVBSORT API Description

Technical Support

Legal Matters


What It Does

AAVBSORT.DLL provides a group of simple to use subroutines to sort Visual Basic arrays. Since the subroutines are written in C++, they are much faster than the same sort done in Visual Basic. Included  are two types of sort routines: SortAry which sorts the array elements themselves and SortIdx which sorts arrays via an index. Array elements can be: Integer, Long, Single, Double, Currency, String, or Fixed String. In the registered version, arrays elements can be of User defined types.

AAVBSORT.DLL is distributed as Shareware. Try before you buy. If you continue using it, you are expected to register.


Quick Start Example

'Make sure the file AAVBSORT.DLL is in your DOS Path

'Put the line below in the declaration section of a form

Declare Sub SortAryDouble Lib "AAVBSORT.DLL" ( a() As Double )

' Put the following in the startup for a form

Dim d(30) as Double

Dim i as Integer

For i=0 to 30

d(i)= rnd

Next i

' Sort the array it-self

SortAryDouble d()

' Display the results on the form

For i=0 to 30

me.print d(i)

Next i


Benefits of Registering

•	Additional sort routines for User defined types.

•	Additional production DLL; smaller, faster, and has the error trapping messages used by the Visual Basic programmer for debugging removed. This will allow you to distribute a truly professional version of your Visual Basic program.

•	License to distribute the production DLL as part of your Visual Basic program.

•	No Shareware nag screen on start-up and exit.

•	Easily printable documentation in MS-Write and MS-Word V2 format.

•	Technical support via FAX, CompuServe, or Internet mail for one year.

•	You will be notified when new versions are available.

•	You will have special reduced prices for new versions.

•	Source code and a license to distribute a modified version of the production DLL as part of your Visual Basic program.


How to Register

For your convenience, a file ORDER.TXT is included in this distribution. Just edit it and print it off.

Registration can be made in U.S. dollars, Pounds Sterling, or in French Francs. Please check the payment option:

|_|	U.S. dollars plus $5.00 shipping and handling,

|_|	150F French plus 30F shipping and handling

|_|	19 Pounds Sterling plus 3 Pounds shipping and handling.

At this time we can accept cash or checks drawn in one of the above currencies. Please make your checks payable to: C. Scott Willy.

Send to:

C. Scott Willy
AA-Software International
12 ter Domaine Du Bois Joli
06330 Roquefort-Les-Pins, France

Tel: (+33) 93.77.50.47
Fax: (+33) 93.77.19.78
Internet: cswilly@acm.org
CompuServe: 100343,2570
X400:	(C=US; A=CompuServe; P=csmail; D=ID:100343,2570)


Installing AAVBSORT

There are three versions of the AAVBSORT DLL. One comes with the Shareware distribution. The development and production versions come when you register. Make sure the version you want to use is on the DOS path and has the  name AAVBSORT.DLL.

Shareware Version

Copy AAVBSORT.DLL to a directory on the DOS path, in the Windows directory or in the System directory.

Registered Version

Make sure the Shareware version is no longer in a directory on the DOS path, in the Windows directory or in the System directory.

Copy AAVBSORT.DEV to a directory on the DOS path, in the Windows directory or in the System directory and rename it AAVBSORT.DLL.

For Distribution

If you are registered, you may distribute the production version of the sort DLL, AAVBSORT.PRO, with your Visual Basic program.

Make sure that neither the Shareware version or the development version of the DLL are in a directory on the DOS path, in the Windows directory or in the System directory.

Copy AAVBSORT.PRO to a directory on the DOS path, in the Windows directory or in the System directory and rename it AAVBSORT.DLL.


AAVBSORT API Description

There are two families of routines, SortAry and SortIdx. The next sections show how to use them, what error checking is done, and some hints when to use one or the other are given. Then the special considerations needed to sort arrays of fixed strings and User defined types are given.

The DLL has various versions. These are described along with the routine to access version information. Finally, there is short listing of the limitations of Visual Basic arrays that you may encounter.

The declarations for all routines have be placed in the file AAVBSORT.TXT. Note that the syntax for fixed string and User defined type arrays must be changed by the programmer (see Fixed Strings and User Defined Types).

Sort an Array In-place (SortAry)

Sort an Array Via an Index (SortIdx)

Fixed Strings

User Defined Types (Registered Versions Only)

Version Information

Limitations


Sort an Array In-place (SortAry)

The are eight routines with the SortAry prefix. The names of the routines for the simple types are:

Declare Sub SortAryCurrency Lib "AAVBSORT.DLL" (array_c() As Currency)

Declare Sub SortAryDouble Lib "AAVBSORT.DLL" (array_d() As Double)

Declare Sub SortAryInteger Lib "AAVBSORT.DLL" (array_i() As Integer)

Declare Sub SortAryLong Lib "AAVBSORT.DLL" (array_l() As Long)

Declare Sub SortArySingle Lib "AAVBSORT.DLL" (array_f() As Single)

Declare Sub SortAryString Lib "AAVBSORT.DLL" (array_s() As String)

The names for fixed strings and User defined types will depend on the programmer (see Fixed Strings and User Defined Types).

How to Use

Error Checking

Pros and Cons of Use


How to Use

All SortAry routines are passed a single argument, the array to be sorted. The type of array to be sorted must match the element type suffix (e.g. Long in SortAryLong). Example:

Dim c(100) as Currency

SortAryCurrency c()


Error Checking

SortAry will only accept an array of a single dimension. An error message is generated if it is passed an array with more.


Pros and Cons of Use

SortAry is inherently faster than SortIdx for arrays with small elements. (i.e. SortAryInteger, SortAryLong, SortArySingle, SortAryDouble). SortAry is notably slow (compared to SortIdx) for dynamic strings (SortAryString).


Sort an Array Via an Index (SortIdx)

There are eight routines with the SortIdx prefix. The names of the routines for the simple types are:

Declare Sub SortIdxCurrency Lib "AAVBSORT.DLL" (array_c() As Currency,
indexArray() As Integer)

Declare Sub SortIdxDouble Lib "AAVBSORT.DLL" (array_d() As Double,
indexArray() As Integer)

Declare Sub SortIdxInteger Lib "AAVBSORT.DLL" (array_i() As Integer,
indexArray() As Integer)

Declare Sub SortIdxLong Lib "AAVBSORT.DLL" (array_l() As Long,
indexArray() As Integer)

Declare Sub SortIdxSingle Lib "AAVBSORT.DLL" (array_f() As Single,
indexArray() As Integer)

Declare Sub SortIdxString Lib "AAVBSORT.DLL" (array_s() As String,
indexArray() As Integer)

The names for fixed strings and User defined types will depend on the programmer (see Fixed Strings and User Defined Types).

How to use

Error Checking

Pros and Cons Of Use


How to use

All SortIdx routines are passed two arguments: the source array and the index array. The source array is not changed, but its values are used for the comparison. The elements in the index array are used to index into the source array and they are sorted. The type of array to be sorted must match the element type suffix (e.g. Long in SortIdxLong). Example:

Dim index(100) as Integer

Dim c(100) as Currency

SortAryCurrency c(), index()


Error Checking

SortIdx will only accept an array of a single dimension. An error message is generated if it is passed an array with more.

The Array is not sorted if:

1.	the upper and lower bounds of array() do not match the bounds of index().

2.	the values in index() are not between the upper and lower bounds of array() (inclusive).

If the values in index() are all zero (indicating it was newly created), then the SortIdx routines will initialize it from lower bound to upper bound and then sort it. This is provided as a convenience to the VB programmer.


Pros and Cons Of Use

SortIdx is inherently faster than SortAry for arrays with large elements (i.e. SortAryCurrency, SortAryString, SortAryFixString, and SortAryUserType).

SortIdx is useful when you are keeping several arrays in parallel. By only sorting the index, it allows you to keep the consistency across multiple parallel arrays. You often want to use parallel arrays (rather than user defined types) to keep under the array size limitations of Visual Basic.


Fixed Strings

Arrays of any specified sized fixed strings can be sorted. As with the simple types, there are two type of sort routines for fixed strings: SortAry and SortIdx.

How to Use

Error Checking


How to Use

You must create a declaration that matches the specific fixed string you are using. In the file AAVBSORT.TXT are sample declarations for fixed string element sized of 15, 40, 80, and 255 characters.

For example, an array of fixed string elements with a length of 35 characters would have the following declarations:

Dim array(100) As String * 35

'The following must be all on one line

Declare Sub SortAryFixed35String Lib "AAVBSORT.DLL" Alias
SortAryFixedString" (a() As String * 35)

SortAryFixed35String array()

The string length in the array definition must match the subroutine declaration. This name of the routine, SortAryFixed35String, is facultative only.


Error Checking

The fixed string sorts have the same error checking as the simple types.


User Defined Types (Registered Versions Only)

Arrays of with User defined types be sorted. As with the simple types, there are two type of sort routines for User defined types: SortAry and SortIdx.

How to Use

Error Checking


How to Use

You must create a routine declaration that uses your user defined type. Secondly, when you call this routine, you must pass a string that describes your user defined type.

To describe an User defined type, you use normal Visual Basic data type names and separate them by a comma. Valid type names are: Integer, Long, Single, Double, Currency, and String. Use the normal Visual Basic convention of String*n to define a Fixed String of n characters.

Below is an example:

'Declare the User Defined Type

Type TEST

   s  As String

   fs As String * 5

   l  As Long

   i  As Integer

   c  As Currency

End Type

'Define a constant that describes User Defined Type TEST

'Must be all on one line

Global Const TestTypeDeclaration_c = "String, String*5, Long, Integer, Currency"

'Define array to sort and a index for it.

Dim array(100) As TEST

Dim index(100) as Integer

'Declare SortAry subroutines for TEST

'Must be all on one line

Declare Sub SortAryTest Lib "AAVBSORT.DLL" Alias "SortAryUserType" (
a() As TEST, ByVal typeDeclaration As String,
ByVal elementIndexToSortOn As Integer)

Declare Sub SortIdxTest Lib "AAVBSORT.DLL" Alias "SortIdxUserType" (
a() As TEST, ByVal typeDeclaration As String,
intArray() As Integer, ByVal elementIndexToSortOn As Integer)

'Sort the array and then the index

SortAryTest array(), TestTypeDeclaration_c, 1

SortIdxTest array(), index(), TestTypeDeclaration_c, 1

It is imperative that the string you pass when calling the sort routines accurately describes the user defined type. If it does not, the sort routines will not work correctly at best and at worst will create a GPF (general protection fault!).

It is a good idea to create a constant (in this case TestTypeDeclaration) that matches the user defined type and keep it near to the type. This way when you change the type definition, you will be reminded to change the constants.


Error Checking

The sort routines for user defined types have the same error checking as the simple types. In addition, they check that the array element length matches the sum of the user defined type described in the typeDeclaration string.


Version Information

The DLL provides a routine, Version, that returns a Visual Basic string with information about the DLL.

Declare Function Version Lib "AAVBSORT.DLL" (ByVal whichInfo As Integer) As String

The following are valid values for whichInfo and what is returned

Value	Description of What is Returned
0	Version information formatted ready to display
1	Program Name
2	Version Number
3	Version Date
4	Type of DLL: Test or Production version


Limitations

Visual Basic has the following relevant limitations on arrays.

•	Maximum number of elements for VB array is 32767.

•	Array index can start from -32768 to 32767.

•	String arrays can only have 64k characters in total (this limit does not apply to fix string arrays).

A complete description of limitations is in Microsoft's Visual Basic Programmers Guide, Appendix D.


Technical Support

All registered owners of AAVBSORT.DLL have one year of technical support available via Fax, electronic mail or surface mail.

Contacting Technical Support

Internet
cswilly@acm.org

CompuServe
100343,2570

X400
(C=US; A=CompuServe; P=csmail; D=ID:100343,2570)

Fax
(+33) 93.77.19.78

Surface Mail
AA-Software International
12 ter Domaine Du Bois Joli
06330 Roquefort-Les-Pins, France


Legal Matters

Definition of Shareware

Association of Shareware Professionals (ASP) Ombudsman Statement

LIMITED WARRANTY AND LICENSE AGREEMENT

Copyright © 1994 AA-Software International


Definition of Shareware

Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual.

Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware.

Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it.


Association of Shareware Professionals (ASP) Ombudsman Statement

This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the Shareware principle works for you. If you are unable to resolve a Shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442-9427 USA, FAX 616-788-2765 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536.


LIMITED WARRANTY AND LICENSE AGREEMENT

NO WARRANTIES.  Users of AAVBSORT.DLL must accept this disclaimer of warranty: "AAVBSORT.DLL is supplied as is.  The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of AAVBSORT.DLL. The entire risk arising out of use or performance of AAVBSORT.DLL remains with the User."

CUSTOMER REMEDIES.  AA-Software International's entire liability and your exclusive remedy shall not exceed the registration fee for AAVBSORT.DLL.

REGISTRATION AND USE. AAVBSORT.DLL is a "Shareware program" and is provided at no charge to the user for evaluation.  Feel free to share it with your friends, but do not give it away altered or as part of another system.  The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products.  If you find this program useful and find that you are using AAVBSORT.DLL and continue to use AAVBSORT.DLL after a reasonable trial period, you must make a registration payment to AA-Software International.

The registration fee will license one copy of the Development version of AAVBSORT.DLL for use on any one computer at any one time.  You must treat this software just like a book.  An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time.

The registration fee will license you to distribute the Production version of AAVBSORT.DLL with your Visual Basic program for use on any number of computers. The registration fee will license you to use the provided source code and to distribute a modified Production version of AAVBSORT.DLL with your Visual Basic program for use on any number of computers. The registration fee will NOT license you  to distribute a modified version of AAVBSORT.DLL of any kind for development purpose.

Commercial users of AAVBSORT.DLL must register and pay for their copies of AAVBSORT.DLL within 30 days of first use or their license is withdrawn.  Site-License arrangements may be made by contacting AA-Software International.

DISTRIBUTION. Anyone distributing AAVBSORT.DLL for any kind of remuneration must first contact AA-Software International at the address below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for Shareware distributors, and such distributors may begin offering AAVBSORT.DLL immediately (However AA-Software International must still be advised so that the distributor can be kept up-to-date with the latest version of AAVBSORT.DLL.).

You are encouraged to pass a copy of AAVBSORT.DLL along to your friends for evaluation.  Please encourage them to register their copy if they find that they can use it.  All registered users will receive a copy of the latest version of the AAVBSORT.DLL system.


Copyright © 1994 AA-Software International

AAVBSORT.DLL Version 1.0
Unregistered Shareware Version

Please register by contacting:

AA-Software International
12 ter Domaine Du Bois Joli
06330 Roquefort-Les-Pins, France

Tel: (+33) 93.77.50.47	Internet: cswilly@acm.org
Fax: (+33) 93.77.19.78	CompuServe: 100343,2570
X400:	(C=US; A=CompuServe; P=csmail; D=ID:100343,2570)